home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / utilities / text / man36.lha / Man3.6 / ManPages / Introduction < prev    next >
Encoding:
Text File  |  1995-02-13  |  3.6 KB  |  111 lines
  1.  
  2.                AN INTRODUCTION TO
  3.                ------------------
  4.             WRITING YOUR OWN MANPAGES
  5.             -------------------------
  6.  
  7.  
  8.     Welcome to the AmigaDOS help archive.  This is an archive that 
  9. contains a commodity to handle man pages for Amiga related programs.
  10. These man pages are written by YOU, the users of our favourite computer.
  11. And I invite you to send me your man page of any Amiga software and
  12. whatever else you believe is interesting and relevant to the Amiga.
  13.  
  14.     This document describes:
  15.  
  16.     I.    How to write your man page.
  17.     II.    How to submit your man page.
  18.     III.    How to get copies of new man pages.
  19.     IV.    Disclaimer and legal stuff.
  20.  
  21.  
  22. I.  HOW TO WRITE A MAN PAGE FOR THE ARCHIVE
  23.  
  24.     You do not have to be a "great writer" in order to write a man
  25. page.  All you need is enthusiasm and some experience with the program
  26. you are describing.  
  27.  
  28.     Since no man-like program is provided together with any amiga
  29. model and everyone sometimes has questions about some software, by writing
  30. a man page you are doing a great service for all your friends in the Amiga
  31. community!  Your man page will be added to the man archive which will be
  32. updated on AMINET frequently, so everyone can use it.
  33.  
  34.     No matter what kind of software you describe, always include the
  35. following information in the man page:
  36.  
  37.     o    The name of the software.
  38.  
  39.     o    The name, address, and e-mail address (if applicable) of 
  40.         the author.
  41.  
  42.     o    A short description (1 or 2 sentences) of the program.
  43.     
  44.     o       Your name, address, and e-mail address (if applicable).
  45.  
  46. In addition, please:
  47.  
  48.     o    Proofread your man page.  Run it through a spelling checker
  49.         and re-read the whole thing before submitting it.
  50.  
  51.     o    Keep all your lines of text shorter than 80 characters.
  52.  
  53.     o    Remember to use proper capitalization.  For example,
  54.         "RAM" and "ROM" are in all capitals because they are
  55.         abbreviations; use "MB" for megabytes, not "Mb" nor "mb"
  56.         which mean megaBITS (same for K=Kilobytes, k=kilobits);
  57.  
  58.     o    Try to avoid abbreviations and slang that are unique to your
  59.         country.  Remember that people all over the world will read
  60.         your man page.
  61.  
  62.     o    Make program names noticeable.  For example, the sentences
  63.  
  64.             I did a list on devs.
  65.             Double-click on edit to invoke se.
  66.  
  67.         are more clear if you write:
  68.  
  69.             I did a List on DEVS:.
  70.             Double-click on "edit" to invoke "se".
  71.  
  72.     o    Use tabs, not spaces, for consistent indenting.
  73.  
  74.     o    Put 1 blank line between paragraphs.
  75.  
  76.     o    Put two spaces, not just one, at the end of each sentence.
  77.  
  78.  
  79. II.  HOW TO SUBMIT YOUR MAN PAGE TO THE ARCHIVE
  80.  
  81.     'Man' is frequently updated on AMINET.  The author will gather some
  82. man pages, include them in the archive, and upload it to AMINET.
  83.  
  84.     Mail your completed man page to:
  85.  
  86.         m_hillen@informatik.uni-kl.de
  87.  
  88.     In addition, if you want to discuss something with me about a
  89. man page, send mail to the same e-mail address.
  90.  
  91.     Do not worry whether your man page will be accepted or not.  As long
  92. as your review is accurate and clear, it will almost definitely be accepted.
  93. My job is really to help make the man pages look "standard" and readable.
  94.  
  95.  
  96. III.  HOW TO GET COPIES OF NEW MAN PAGES
  97.  
  98.     As 'man' is uploaded to AMINET frequently, you just have to download
  99. it to get the newest man pages.  If you need help using ftp, please ask a 
  100. user consultant or systems administrator at your site.
  101.  
  102.  
  103. IV.  LEGAL STUFF
  104.  
  105.     As only very few software companies allow to copy parts of their
  106. manuals, the writer of a man page has to write down a text in his OWN
  107. words.  Only the writer of a man page can be made responsible for any
  108. illegal copy of a manual.  Therefore I will only accept man pages where
  109. the writer´s name, address, and e-mail address (if applicable) are added.
  110.  
  111.